home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Libraries / stdwin / Doc / man / editwin.man < prev    next >
Encoding:
Text File  |  1988-06-23  |  8.6 KB  |  302 lines  |  [TEXT/????]
  1. .TH EDITWIN 3
  2. .SH NAME
  3. Editwin \- editing windows package for STDWIN
  4. .SH SYNOPSIS
  5. .nf
  6. .ft C
  7. #include "stdwin.h"
  8. #include "editwin.h"
  9.  
  10. typedef struct editwin {
  11.     WINDOW *win;
  12.     TEXTEDIT *tp;
  13.     char *filename;
  14.     char saved;
  15. } EDITWIN;
  16.  
  17. EDITWIN *ewcreate(char *filename);
  18. EDITWIN *ewnew();
  19. EDITWIN *ewopen();
  20.  
  21. bool ewsave(EDITWIN *ew);
  22. bool ewsaveas(EDITWIN *ew);
  23. bool ewsavecopy(EDITWIN *ew);
  24. bool ewsaveall();
  25. bool ewrevert(EDITWIN *ew);
  26. bool ewclose(EDITWIN *ew);
  27. bool ewcloseall();
  28.  
  29. bool ewwritefile(EDITWIN *ew, char *filename);
  30. bool ewreadfile(EDITWIN *ew, char *filename);
  31.  
  32. bool ewevent(EDITWIN *ew, EVENT *e, int *closed_return);
  33. void ewreplace(EDITWIN *ew, char *str);
  34. void ewundo(EDITWIN *ew); /* Not implemented */
  35. void ewcopy(EDITWIN *ew);
  36. void ewpaste(EDITWIN *ew);
  37.  
  38. EDITWIN *ewfind(WINDOW *win);
  39. int ewcount();
  40. .ft 1
  41. .fi
  42. .SH DESCRIPTION
  43. .I Editwin
  44. is a package built on top of the
  45. .I textedit
  46. package, to ease the construction of views on text files etc.
  47. Many calls exist to make it extremely simple to respond to standard
  48. menus of
  49. .B File
  50. operations (New, Open..., Save, etc.) and
  51. .B Edit
  52. operations (Cut, Copy, Paste).
  53. .PP
  54. Below are descriptions of the individual functions.
  55. Note that when a reference is made to a window's contents, the entire
  56. contents of the edit buffer belonging to the window is meant, not just
  57. the part of it visible in the window.
  58. .IP ewcreate
  59. If
  60. .I filename
  61. is a nil pointer, this call creates an ``Untitled'' edit window.
  62. Otherwise, the specified file must exist, and an edit window showing
  63. its contents is created.
  64. In both cases, the window's `saved' flag is set initially.
  65. A pointer to a newly allocated EDITWIN struct is returned.
  66. If something went wrong (e.g., insufficient memory, or an unreadable
  67. file was specified), a nil pointer is returned.
  68. .IP ewnew
  69. This function can be called in response to the selection of the
  70. .B New
  71. menu item.
  72. It is equivalent to a call to
  73. .I ewcreate((char*)0).
  74. .IP ewopen
  75. Call this function for the
  76. .B Open...
  77. menu item.
  78. It asks the user for an existing file name (using
  79. .IR waskfile ),
  80. and then calls
  81. .I ewcreate
  82. with that file name as parameter.
  83. It returns nil if the dialog was cancelled or
  84. .I ewcreate
  85. returns nil.
  86. .IP ewsave
  87. Call this function for the
  88. .B Save
  89. menu item.
  90. If the window's contents were modified since they were last read or
  91. saved, the function attempts to save the window to its file.
  92. If the window was still ``Untitled'', the user is first asked to specify
  93. a file name.
  94. The function returns true (nonzero) if the contents were actually saved,
  95. or didn't need saving.
  96. .IP ewsaveas
  97. Call this function for the
  98. .B Save As...
  99. menu item.
  100. It asks the user for a new file name to save the window's contents, and
  101. if the saving succeeds, sets this to be the file name to which future
  102. save operations are directed.
  103. .IP ewsavecopy
  104. Call this function for the
  105. .B Save a Copy...
  106. menu item.
  107. Like
  108. .IR ewsaveas ,
  109. this function asks file a new file name and saves the window's contents
  110. to that file; but it does not change the file name used for future save
  111. operations.
  112. .IP ewsaveall
  113. Calls
  114. .I ewsave
  115. for all windows.
  116. If any call returns false (zero),
  117. .I ewsaveall
  118. skips further calls and returns false.
  119. .IP ewrevert
  120. Call this function for the
  121. .B Revert...
  122. menu item.
  123. It attempts to undo any changes since the window was last read or
  124. saved, by re-reading the corresponding file.
  125. If this is at all possible, the user is asked to confirm the operation
  126. first (since it may destroy valuable changes).
  127. The function returns true if the file was actually read back, or if the
  128. window was unchanged with respect to the file.
  129. .IP ewclose
  130. Closes the window.
  131. If the window was changed since it was last read or saved, the user is
  132. first asked whether it should be saved, and if the answer is Yes,
  133. .I ewsave
  134. is called.
  135. Cancelling the dialog will prevent closing the window.
  136. Returns true if the window was actually closed.
  137. .IP ewcloseall
  138. Calls
  139. .I ewclose
  140. for all windows.
  141. If any call returns false,
  142. .I ewcloseall
  143. skips further calls and returns false.
  144. .IP ewwritefile
  145. Writes the contents of the edit window to the specified file.
  146. Returns true if the operation succeeded.
  147. This does
  148. .I not
  149. set the `saved' flag for the window (because it is used internally be
  150. .IR ewsavecopy ).
  151. .IP ewreadfile
  152. Reads the contents of the given file into the edit window, discarding
  153. its previous contents.
  154. Returns true if the operation succeeded.
  155. This
  156. .I does
  157. set the `saved' flag for the window.
  158. .IP ewevent
  159. Call this function in response to
  160. .I any
  161. event returned by
  162. .I wgetevent.
  163. If the event is a non-menu event applicable to the specified window, it
  164. is handled and the function returns true;
  165. otherwise nothing is done and the function returns false.
  166. (Menu events cannot be handled this way because the editwin package
  167. doesn't create its own menus, and thus cannot know the menu IDs or the
  168. numbers of the menu items.)
  169. If the first parameter is a nil pointer, the event is checked against
  170. any edit window; otherwise, only events applying to the given window are
  171. handled.
  172. The third parameter must be a pointer to an integer variable, which is
  173. cleared normally when an event was handled, but set to true when a
  174. window was closed as a consequence of the event (it is unchanged when
  175. the event was nbot handled at all).
  176. In the latter case, the caller should check whether any windows are
  177. still open (see
  178. .IR ewcount ),
  179. and if this is not the case, it should either exit or open a new window.
  180. This function clears a window's `saved' flag whenever its contents are
  181. modified by the event's handling.
  182. .IP ewreplace
  183. Replaces the current text selection in the window by the given
  184. (null-terminated) string.
  185. This will insert text if the text selection was an insert point.
  186. .IP ewundo
  187. Reserved for future extension of the package with an Undo facility.
  188. .IP ewcopy
  189. Call this function for the
  190. .B Copy
  191. menu item.
  192. It retrieves the contents of the window's text selection, if non-null,
  193. and copies it in into the clipboard through a call to
  194. .I wsetclip.
  195. It beeps if the text selection is empty.
  196. (To implement the
  197. .B Cut
  198. menu item, call
  199. .I ewcopy
  200. followed by
  201. .IR "ewreplace(ew, ``'')" .)
  202. .IP ewpaste
  203. Call this function for the
  204. .B Paste
  205. menu item.
  206. It retrieves the contents of the clipboard, if non-null,
  207. and pastes it into the window through a call to
  208. .I ewreplace.
  209. It beeps (and does not change the window's contents) if the clipboard is
  210. empty.
  211. .IP ewfind
  212. Returns a pointer to the EDITWIN struct containing the given WINDOW
  213. pointer; returns nil if none exists.
  214. .IP ewcount
  215. Returns the number of open edit windows.
  216. .SH EXAMPLE
  217. The following program is a trivial but almost usable single-file text
  218. editor.
  219. Usage is ``program [file]''.
  220. .nf
  221. .ft C
  222.  
  223. #include "stdwin.h"
  224. #include "editwin.h"
  225.  
  226. main(argc, argv) int argc; char **argv; {
  227.     EDITWIN *ew;
  228.     winitnew(&argc, &argv);
  229.     if (argc <= 1) ewnew();
  230.     else           ewcreate(argv[1]);
  231.     for (;;) {
  232.         EVENT e;
  233.         int closed;
  234.         wgetevent(&e);
  235.         if (ewevent(ew, &e, &b) && closed) break;
  236.     }
  237.     wdone();
  238.     exit(0);
  239. }
  240. .ft 1
  241. .fi
  242. .SH HINTS
  243. The members of the EDITWIN data structure are explicitly intended to be
  244. accessible to the caller.
  245. Functionality which is not provided directly but which is available for
  246. plain windows or for textedit data structures can be implemented by
  247. applying it to the
  248. .I win
  249. or
  250. .I tp
  251. members.
  252. Note that the
  253. .I filename
  254. member, when non-nil, points to memory allocated with
  255. .IR malloc (3).
  256. .PP
  257. Changes to the window's contents should preferably be made with
  258. .I ewreplace,
  259. since it manages the `saved' flag.
  260. .PP
  261. To control the text attributes used in an EDITWIN window, you can set
  262. them globally before creating the window.
  263. .SH DIAGNOSTICS
  264. .I Ewcreate, ewnew
  265. and
  266. .I ewopen
  267. return nil when the user cancelled the operation or when they could not
  268. get all the necessary memory.
  269. The save, revert, close and read/write family of functions return FALSE
  270. if the operation was canceled by the user or if the file I/O failed.
  271. .I Ewevent
  272. returns TRUE when it has processed the event.
  273. .PP
  274. .I Ewcreate
  275. and
  276. .I ewopen
  277. warn the user if a file is larger than about 30K; the textedit package
  278. was not designed to operate on big files, and may be intolerably slow.
  279. .SH SEE ALSO
  280. STDWIN documentation
  281. .br
  282. textedit(3)
  283. .SH AUTHOR
  284. Guido van Rossum
  285. .SH BUGS
  286. .I Editwin
  287. inherits some bugs from the
  288. .I textedit
  289. package.
  290. .br
  291. The package doesn't detect the situation where the user opens the same
  292. file twice, edits both copies, and saves them, thus losing the
  293. changes to the copy saved first.
  294. .br
  295. If the height of the document gets over 32K scan lines, you are
  296. in trouble: most window systems limit coordinates to short integers.
  297. .br
  298. Missing functionality:
  299. a way to specify an alternate title for an untitled window;
  300. a way to create a non-file window, which isn't saved when closed.
  301. (These should be easy to add, given the simplicity of the source.)
  302.